home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / X11 / xmbase-grok-1.2 / grok.hlp < prev    next >
Text File  |  1995-06-25  |  61KB  |  1,342 lines

  1. %% intro
  2.     INTRODUCTION
  3.  
  4.     Grok is a program to present unstructured data in a row/column format
  5.     using an index card paradigm. Each database row (line) is a card; each
  6.     database column (field) is an item in the card. Items can be presented
  7.     in the card as various types and shapes. The presentation of a database
  8.     is determined by a "form".
  9.  
  10.     The concepts of "forms" and "databases" are separate. Forms are created
  11.     once, and determine the layout and presentation of the unstructured
  12.     data in the database. Each form references a database. A database may
  13.     be referenced by more than one form. To select a database for display
  14.     and editing, use the Database pulldown (actually, the database pulldown
  15.     lists forms, which reference the databases; the name "form" in the menu
  16.     bar may be too non-obvious for users not concerned with the man behind
  17.     the curtain).
  18.  
  19.     Creating or changing a form is a more involved process that needs to be
  20.     done only when a new type of database is created. Normally, users only
  21.     work with existing forms, using them to edit data in databases. For
  22.     more information on creating or changing forms, refer to the User's
  23.     Manual.
  24.  
  25.     Assuming that the form already exists, the first step is choosing a
  26.     form (database) to display and edit. This can be done with the Database
  27.     pulldown, or by naming the form (database) on the command line, as in
  28.  
  29.         grok phone
  30.  
  31.     The window will resize itself to accomodate the card, and all cards
  32.     in the database will be listed in the summary area. The first card
  33.     will also be displayed in the card area at the bottom of the window.
  34.     The selection of cards displayed in the summary can be changed with
  35.     the Search button or the Query pulldown. A different card can be
  36.     displayed in the card area by pressing the left mouse button on a line
  37.     in the summary, or by using the next/previous arrows at the bottom
  38.     left of the window.
  39.  
  40.     To edit a card, simply press on the inset button or green radio/flag
  41.     button to be changed. Editable text buttons are pink, read-only text
  42.     buttons are gray (as an exception, large "note" text entry areas are
  43.     always gray). Shaded (grayed-out) buttons cannot be accessed because
  44.     some condition specified by the form designer is not met. After changing
  45.     a card, it must be written back to disk by choosing Save or Quit in the
  46.     File pulldown. Choosing another database from the Database pulldown
  47.     also writes back. A blank card can be added to the database by pressing
  48.     the New button; the Delete button (irreversibly) deletes a card.
  49.  
  50.     The actual meaning of buttons and items in the card area is completely
  51.     up to the form designer.
  52. %% trouble
  53.     TROUBLESHOOTING
  54.  
  55.     *  On SGI systems, if the icon doesn't show a picture, copy the icon
  56.         picture Grok.icon into your ~/.icons directory. If you don't have
  57.         one and don't want one, set the grok*noIcon resource to False in
  58.         your ~/.Xdefaults file. It may be necessary to restart 4Dwm to
  59.         register the icon after copying it to ~/.icons.
  60.  
  61.     *  The grok program uses quite a few colormap entries. Although there
  62.         is a black&white fallback mode, you may have problems starting other
  63.         programs that also need many colormap entries. The only workaround
  64.         is to kill grok when you don't need it.
  65.  
  66.     *  If radio and toggle buttons appear gray regardless of the colToggle
  67.         resource, make sure that the sgiMode resource is False.
  68.  
  69.     If you have problems you can't resolve, or if you have suggestions
  70.     for new features, or porting instructions for new platforms, send mail
  71.     to me at thomas@bitrot.in-berlin.de.
  72.  
  73.     IF YOU MAIL, DO NOT FORGET TO INCLUDE YOUR VERSION NUMBER
  74.     AS REPORTED BY "grok -v". If you ask me for patches or files, also tell
  75.     me whether you have the gzip compression program.
  76.  
  77.     Mail me to subscribe to the mailing list, grok@bitrot.in-berlin.de.
  78. %% files
  79.     FILES AND PROGRAMS
  80.  
  81.     Grok searches for forms and databases in four places and presents them
  82.     in the Database pulldown in the order they are found: the current
  83.     directory, ./grokdir, ~/.grok, and GLIB/grokdir (GLIB stands for the
  84.     GLIB path set in the Imakefile or Makefile.alt when grok was compiled;
  85.     the default is /usr/local/lib). The path the current database was read from
  86.     can be displayed with Help->Database.
  87.  
  88.     Grok stores all forms in the ~/.grok directory, unless a full path is
  89.     given in the top two lines of the form editor. Forms determine the
  90.     presentation of data in cards. Form files have a .gf extension. By
  91.     default, the databases themselves are stored in the path defined by
  92.     the form if it begins with / or ~. If it doesn't, the database is searched
  93.     for in the directory the form was read from. Databases have a .db
  94.     extension. Multiple forms may reference the same database. Forms
  95.     may also reference databases elsewhere, or no databases at all in the
  96.     case of procedural databases. The ~/.grok directory also contains the
  97.     .grokrc file, which stores preferences.
  98.  
  99.     Form files and the preferences file are strictly Ascii. Databases are
  100.     usually also Ascii, but need not be. When editing Databases with a text
  101.     editor, make sure to properly escape field and line delimiters with
  102.     backslashes, or great chaos will result.
  103.  
  104.     The grok executable itself is stored in the GBIN directory; the grok.hlp
  105.     file and the public grokdir directory (see above) are stored in the GLIB
  106.     directory. Both GBIN and GLIB are defined in the Imakefile or Makefile.alt.
  107.     The defaults are /usr/local/bin and /usr/local/lib, respectively.
  108.  
  109.     The distribution contains a color icon image file Grok.icon in SGI RGB
  110.     format. It should be copied to ~/.icons. This only works on SGI systems.
  111.     There is also a Grok.fti file that is an SGI-conforming desktop icon.
  112. %% help
  113.     GETTING HELP
  114.  
  115.     To get general help on a popup menu, press the Help button in that
  116.     popup menu.
  117.  
  118.     To get help on a pulldown menu in the main window, install the pulldown
  119.     menu by pressing and releasing the left mouse button on the menubar
  120.     button, then press the HELP or F1 keyboard key. The Database, Sort, and
  121.     Query pulldowns are completely determined by the author of the form
  122.     which describes the database, they are not grok features. Grok only
  123.     adds the "All" entry into the Query menu which puts all cards into the
  124.     summary list.
  125.  
  126.     Help on most buttons is available by choosing "On Context" in the Help
  127.     pulldown, and then pressing on a button or field. Every help window
  128.     contains a Context button that does the same thing as "On Context".
  129. %% resources
  130.     VARIABLES AND X RESOURCES
  131.  
  132.     grok uses the following environment variables:
  133.  
  134.        GROK_FORM defines a directory that is searched for *.gf form files to
  135.        be put into the database pulldown. This directory is searched first.
  136.        It replaces the default directory ".".
  137.  
  138.        GROK_PATH is another directory to find files such as grok.hlp.
  139.  
  140.        PATH is searched next if a file is not found in $GROK_PATH.
  141.  
  142.        HOME is substituted for "~" in paths.
  143.  
  144.        USER is used if the "user" keyword is used in an expression.
  145.  
  146.     To get a list of default X resources of the "grok" program, run it with
  147.     the -d option. The output can be directly appended to the .Xdefaults
  148.     file in your home directory or saved into a file "Grok" in your
  149.     app-defaults directory. If you install a system wide app-default file
  150.     make sure that lines do not start with "grok"; otherwise users might
  151.     not be able to override the setup. Omit the application name or use
  152.     the application class name "Grok".
  153.  
  154.         noIcon: don't draw anything into the icon. This should be used on
  155.         SGI systems so that 4Dwm uses the color picture as an icon.
  156.         The color icon should be moved to ~/.icons/Plan.icon .
  157.         background: background color for all menus
  158.         colStd: foreground color for text
  159.         colSheet: background color for help and print-window windows
  160.         colBack: gray background color for uneditable text, and charts
  161.         colTextBack: pink background color for editable texts
  162.         colToggle: color of toggle and flag buttons
  163.         colCanvBack: background of card canvas in form editor
  164.         colCanvFrame: color of item frames in card canvas in form editor
  165.         colCanvBox: blue item box color in card canvas in form editor
  166.         colCanvSel: yellow for selected items in card canvas in form editor
  167.         colCanvText: color of text in items in card canvas in form editor
  168.         colChartAxis: color of X/Y axis and axis labels of charts
  169.         colChartGrid: color of grid lines subdividing charts
  170.         colChartBox: color of outline of bars in charts
  171.         colChart0..7: available colors of chart bars
  172.         sgiMode: if False on IRIX 5.x systems, do not use the desktop look
  173.         useSchemes: on IRIX 5.x systems, Lascaux or some other color scheme
  174.         menubar*fontList: font for menubar and pulldowns
  175.         fontList: default font for buttons and titles
  176.         helpFont: small font used for help windows
  177.         helvFont: "Helv" font used in cards if selected in form editor
  178.         helvObliqueFont: "HelvO" font used in cards if selected in form editor
  179.         helvSmallFont: "HelvS" font used in cards if selected in form editor
  180.         helvLargeFont: "HelvB" font used in cards if selected in form editor
  181.         courierFont: "Courier" font used in cards if selected in form editor,
  182.         must be fixed-width, is also used in the summary
  183.         labelFont: font used for charts
  184. %% help_ctx
  185.     CONTEXT
  186.  
  187.     To get help for a button, press the Context button, and then the
  188.     button you need help for. This button is equivalent to the On Context
  189.     item in the help pulldown.
  190. %% help_done
  191.     DONE
  192.  
  193.     Remove the help popup.
  194. %% pd_file
  195.     FILE PULLDOWN
  196.  
  197.     Print:
  198.          Print selected cards to printer or files.
  199.  
  200.     Preferences:
  201.          Pops up a window that allows changing the global configuration.
  202.  
  203.     Form Editor:
  204.          Edit current form:
  205.             Start the form editor on the current database. Editing forms
  206.             means to change the representation of the data in a card, the
  207.             layout and types of card items and the summary format can be
  208.             changed. The "form" is the description of the representation
  209.             of data, while the "database" is a file containing unstructured
  210.             data. Note that editing forms is a rather complicated procedure,
  211.             compared to using the main menu.
  212.  
  213.          Create new form from scratch:
  214.             Clear the main menu and start the form editor with no preset
  215.             form. This is used to start a new form that is different from
  216.             all existing forms. The new form will be put into the Database
  217.             pulldown when it is finished.
  218.  
  219.          Create, use current as template:
  220.             Start the form editor. The current form as selected from the
  221.             Database pulldown provides the defaults. A new form name must
  222.             be entered. This is used to start a new form that is more or
  223.             less similar to an existing form.
  224.  
  225.     About:
  226.          Pops up a window displaying the program version and an address
  227.          to complain to if something doesn't work.
  228.  
  229.     Save:
  230.          Save the current database unconditionally, whether it was modified
  231.          or not. If it was modified, the fact is noted under the Search line. The
  232.          database is also saved if it was modified when Quit is chosen, or if
  233.          a new database is selected from the Database pulldown, or if a form
  234.          editor is started.
  235.  
  236.     Quit:
  237.          Save the current database if it was modified, and exit. This is equivalent
  238.          to double-clicking the mwm corner button. Warning - if grok runs
  239.          under twm, window manager kills will NOT save, and exit without
  240.          warning.
  241.  
  242.     Rambo Quit:
  243.          Quit without saving. Changes made to cards after the last Save
  244.          will be lost. You will be asked to confirm if changes were made.
  245. %% rambo
  246.     RAMBO QUIT
  247.  
  248.     You have made changes to the current database that have not been
  249.     saved to disk. If you want to discard these changes, press OK. If
  250.     you want to save the changes, press Cancel, and choose Quit from
  251.     the File pulldown.
  252. %% pd_dbase
  253.     DATABASE PULLDOWN
  254.  
  255.     Strictly speaking, the pulldown name is a misnomer. Databases are
  256.     unstructured data that need a "form" for defining the presentation
  257.     in a card. The Database pulldown selects a form, which in turn
  258.     references the database itself. For the casual user, this distinction
  259.     is of no consequence, and "Database" seemed to be a more obvious
  260.     name.
  261.  
  262.     Grok searches for databases in four places and presents them in the
  263.     Database pulldown in the order they are found: the current directory,
  264.     ./grokdir, ~/.grok, and GLIB/grokdir (GLIB stands for the GLIB path set
  265.     in the Imakefile or Makefile.alt when grok was compiled; the default
  266.     is /usr/local/lib). Help->Database can be used to show the actual path
  267.     the database was read from, and will be saved to if it is modified.
  268.  
  269.     All files ending in .gf will be put into the database pulldown, with
  270.     the .gf removed. Choosing an item will load the new form and the
  271.     database it references. The window will resize to fit the new card.
  272.  
  273.     If the current database was modified when a new database is loaded,
  274.     it is written back to disk first, as if File->Save had been used.
  275.  
  276.     If the form specifies a default query (added with the Queries button in
  277.     the form editor), only a subset of available cards may be displayed in
  278.     the summary initially. Use Query->All to show all cards.
  279. %% pd_section
  280.     SECTION PULLDOWN
  281.  
  282.     Databases can be divided into sections. If the database file is a
  283.     directory, every file in it or its subdirectories becomes a section.
  284.     When a database is read, all its section files are read. The section
  285.     pulldown can be used to select one or all sections for display in the
  286.     summary list in the main window.
  287.  
  288.     If the database has sections, it is necessary to select a section
  289.     before adding a card. The new card will be put into the current
  290.     section. The card can be moved to another section later with the
  291.     section popup button to the right of the "Delete" button at the
  292.     bottom of the main window (this button only appears if grok is
  293.     compiled with Motif library version 1.2 or greater).
  294. %% pd_sort
  295.     SORT PULLDOWN
  296.  
  297.     Sorts the database by a named database item. The database has no
  298.     inherent order; new cards are simply appended to the end, and a
  299.     database saved (File->Save) after sorting will come up in the same
  300.     order is had when it is reloaded unless the form has a built-in default
  301.     sort (defined with the form editor).
  302.  
  303.     When sorting, leading white space is skipped. If both strings to
  304.     compare are numeric (begin with a digit or a period), they are
  305.     compared numerically. Otherwise, they are compared lexicographically.
  306.     Note that columns of type Date, subtype Time contain both date and
  307.     time, although only the time is shown. The date does figure in the
  308.     sort order.
  309.  
  310.     Most databases have a default sort order that was specified when the
  311.     form was created. When sorting by another column, the default column
  312.     becomes the secondary sort criterium. That is, if a rolodex normally
  313.     sorted by name is re-sorted by group, each group will be sorted by
  314.     name internally.
  315. %% pd_query
  316.     QUERY PULLDOWN
  317.  
  318.     The items of this pulldown determine which cards are shown in the
  319.     summary. The list always begins with All, which puts all available
  320.     cards into the summary. All other items were defined by the designer
  321.     of the form. Except for the "All" query, queries either search all
  322.     cards for matches, or only those already in the summary (if incremen-
  323.     tal searches are enabled in the File->Preferences menu).
  324.  
  325.     To change, add, or delete queries, choose File->Form editor->Edit
  326.     current form, and press the Queries button. That menu also allows you
  327.     to choose a query that is done automatically when the database is
  328.     loaded. Choose Help->Expression grammar for an explanation of query
  329.     expressions.
  330.  
  331.     The search button near the top of the main window offers an alternative
  332.     way of selecting a set of cards to display in the summary. Optionally,
  333.     queries from the Query pulldown can be shown as search strings. Choose
  334.     File->Preferences and press Help for details.
  335. %% search
  336.     SEARCH
  337.  
  338.     Enter a search string and press Return to select a subset of cards to
  339.     be displayed in the summary below the search button. After searching,
  340.     any card can be chosen from the summary by pressing on a line. All
  341.     items of a card are searched that permit searching (this was defined
  342.     when the form that controls the presentation of the card was created).
  343.     Searching is a simple string search. All cards in the database are
  344.     searched for matches, unless incremental searches are enabled in the
  345.     File->Preferences menu, in which case only those cards already in the
  346.     summary are searched.
  347.  
  348.     The last 20 searches are remembered and can be retrieved using the
  349.     previous/next arrow buttons. The Search button is equivalent to
  350.     pressing the Return key in the search string area. Optionally, queries
  351.     from the Query pulldown can be shown as search strings, see the
  352.     File->Preferences popup.
  353.  
  354.     If the search string begins with an opening parenthesis or an opening
  355.     brace, text searching is replaced by an expression search. All cards
  356.     for which the expression does not return an empty string or a string
  357.     beginning with 'f' (if the expression begins with '{') or a numeric value
  358.     0 (if the expression begins with '('). For an explanation of expressions
  359.     and the difference between '{' and '(', choose the Expression Grammar
  360.     item in the Help pulldown.
  361.  
  362.     If the search string is "*", all cards are put into the summary. This
  363.     is equivalent to selecting "All" from the Query pulldown.
  364.  
  365.     All other strings are searched for. Case is not significant.
  366. %% addsect
  367.     ADD SECTION
  368.  
  369.     Databases can have multiple sections, each containing zero or more
  370.     cards. Each section is written to a separate file in a directory
  371.     ~/.grok/databasename. When a section is added, a new empty file is
  372.     created in this directory, with the name of the section followed by
  373.     the extension ".db". If the database did not have sections, the
  374.     directory is created and all cards are moved into the new section;
  375.     otherwise the new section is empty. No sections can be added to a
  376.     procedural database.
  377.  
  378.     Press the Add button to add the new section, or Cancel to abort.
  379. %% info
  380.     INFO LINE
  381.  
  382.     Displays the form (database) name, the number of cards in the summary,
  383.     and the total number of cards. If the database has been modified since
  384.     it was loaded, "(modified)" is displayed. If the database cannot be modified
  385.     because either the database file has no write permission or because the
  386.     form designer specified that the database is read-only (near the top of the
  387.     form editor window), "(read-only)" is displayed.
  388.  
  389.     For more information about the current form and database, choose the
  390.     Database item from the Help pulldown. For an explanation of the
  391.     difference between forms and databases, choose Help->Introduction.
  392. %% pos
  393.     NEXT/PREV
  394.  
  395.     Switch to the next or previous card, by scrolling the highlight in
  396.     the summary up or down. Cards not shown in the summary will be
  397.     skipped. To display all cards in the summary, choose All in the
  398.     Query pulldown.
  399. %% new
  400.     NEW
  401.  
  402.     Create a new blank card. The new card is appended to the end of the
  403.     database; use the Sort pulldown to re-sort. The summary is cleared.
  404. %% del
  405.     DELETE
  406.  
  407.     Delete the current card.
  408. %% dup
  409.     DUP
  410.  
  411.     Create a copy of the current card, append it to the end of the
  412.     database, and display it in the card window for editing. Use the
  413.     Sort pulldown to re-sort.
  414. %% sect
  415.     SECTION
  416.  
  417.     The button displays the section the current card belongs to, if
  418.     there are sections. Press to get a list of defined sections; drag
  419.     the mouse and release to select a section. The card will be moved
  420.     to that new section. If there are no sections, this button stays
  421.     blank. Sections that came from files without write permission are
  422.     grayed out in the popup.
  423. %% summary
  424.     SUMMARY
  425.  
  426.     The summary shows one line for each card that satisfies the selection
  427.     done with the Search button or the Query pulldown. The layout is
  428.     determined by the form, which can be changed with File->Edit Form.
  429. %% letters
  430.     LETTERS
  431.  
  432.     These buttons select all cards whose sorted column begins with the
  433.     respective character. The sorted column is the column the database was
  434.     last sorted by, using the Sort pulldown. Most databases get default-
  435.     sorted when loaded. The search ignores all whitespace and punctuation
  436.     characters except underscores. The letters row can be turned off with
  437.     the File->Preferences menu.
  438.  
  439.     If the `Letter search checks all words' flag in the Preferences menu
  440.     is on, the letter search is modified such that the first letter of all
  441.     words, instead of just the first word, in the sorted column is checked.
  442.     This is useful for people's names to search for first and last initial.
  443.  
  444.     The "misc" button selects all empty columns or words that begin
  445.     with underscores or digits.
  446. %% card
  447.     CARD
  448.  
  449.     The card shows a single line of the database chosen with the Database
  450.     pulldown. First, select a set of cards, using the Search button or the
  451.     Query pulldown. Choose a card from the resulting summary listing by
  452.     selecting it, or use the next/previous arrows to scroll. The New button
  453.     adds an empty card to the database. After editing the card, write the
  454.     database back to disk using the File->Save or File->Quit buttons, or
  455.     by selecting another database from the Database pulldown. For more
  456.     details, choose Introduction from the Help pulldown in the top right corner.
  457. %% print
  458.     PRINT
  459.  
  460.     The print menu prints selected cards of the current database. Databases
  461.     can be selected with the Database pulldown. The order of the cards printed
  462.     is the same as in the summary list. The data is printed by writing to stdin
  463.     of the spooler commands as defined with the Preferences menu, or to a
  464.     file, or to a window.
  465.  
  466.     Cards to print: selects which cards should be printed. Current only
  467.         prints only the card currently displayed in the lower half of the
  468.         main menu. Search or query prints all cards displayed in the
  469.         summary window in the upper half of the main menu, and All
  470.         prints all cards.
  471.  
  472.     Output format: specifies which information to include in the printout.
  473.         Summary generates a simple hardcopy of the summary list in the
  474.         main menu. Summary with notes prints all note fields in addition
  475.         to the summary line, as text blocks below the respective summary
  476.         line. Cards prints all printable data fields in a two-column list.
  477.  
  478.     Output quality: ASCII prints straight ascii text; overstrike ASCII is
  479.         equivalent but uses backspacing to achieve boldface and underlines;
  480.         and PostScript attempts to improve readability by using different fonts
  481.         and lines. Overstrike output is understood by programs such as more
  482.         or less. This setting determines whether the PostScript print spooler
  483.         or the ASCII print spooler, as defined in the Preferences menu, is used.
  484.  
  485.     Output device: Printer sends the data to the spooler as defined in the
  486.         Preferences menu. File writes to a file, and Window creates a
  487.         window and displays the data.
  488.  
  489.     The Print button starts the operation; the Cancel button removes the
  490.     Print popup without generating output. Changed settings in the menu
  491.     are remembered either way.
  492. %% editprint
  493.     PRINT WINDOW
  494.  
  495.     This window was created with the File->Print function. In the print
  496.     panel, the output device was set to Window. Other choices are Printer
  497.     or File. This window is supposed to be a preview. Only plain ASCII
  498.     can be displayed. The contents reflect the selection in Cards to
  499.     print in the print panel. Once installed, the window does not change.
  500. %% msg_clear
  501.     CLEAR
  502.  
  503.     Delete all contents of the editor window. If a file is being displayed,
  504.     it is not deleted; if Clear is pressed by accident use Cancel.
  505. %% msg_delete
  506.     DELETE
  507.  
  508.     Delete all contents of the editor window, and terminate the editor.
  509.     If a file was being displayed in the window, it is deleted on disk.
  510. %% msg_cancel
  511.     CANCEL
  512.  
  513.     Discard all changes to the text and exit the editor without saving.
  514. %% msg_done
  515.     DONE / SAVE
  516.  
  517.     This button is labelled "Save" if the text is editable, and "Done"
  518.     if not. "Save" writes the changes back and terminates the editor.
  519.     "Done" dismisses the window without saving.
  520.  
  521.     This is equivalent to double-clicking the window manager button in
  522.     the top left corner of the window decoration.
  523. %% pref
  524.     PREFERENCES
  525.  
  526.     The preferences menu changes global configuration. The configuration
  527.     data is written to the ~/.grok/.grokrc file when the Done button is
  528.     pressed.
  529.  
  530.     12-hour mode toggles the format of Date items in the card to either
  531.         12-hour am/pm format, or to 24-hour format.
  532.  
  533.     Month/day/year mode toggles the format of Date items in the card to
  534.         either mm/dd/yy format, or to dd.mm.yy format. It also provides
  535.         the default interpretation of input or file dates that contain neither
  536.         slashes nor dots.
  537.  
  538.     Show query search expression, if turned on, will display the search
  539.         expression used by a query when an item from the Query pulldown
  540.         (other than All) is selected. The query expression can then be
  541.         modified manually and re-applied using the Search button.
  542.  
  543.     Enable search by initial letter, if enabled, inserts a row of buttons
  544.         A..Z, `misc', and `all' below the summary that select all cards
  545.         whose sorted column begins with the respective character. The
  546.         sorted column is the column the database was last sorted by, using
  547.         the Sort pulldown. Most databases get default-sorted when loaded.
  548.         The search ignores all whitespace and punctuation characters
  549.         except underscores.
  550.         NOTE: changing this mode takes effect only when grok is restarted.
  551.  
  552.     Incremental searches and queries, if enabled, base every new search,
  553.         query, and letter search on the results of the previous. Instead
  554.         of searching all cards, only those displayed in the summary are
  555.         searched. This does not apply to the "All" search; it always puts
  556.         all cards into the summary.
  557.  
  558.     Letter search checks all words: this flag modifies the letter search,
  559.         if enabled, such that the first letter of all words in the sorted
  560.         column is checked. This is useful for people's names to search for
  561.         first and last initial.
  562.  
  563.     Print spoolers: the system command that is used to print PostScript or
  564.         ASCII, respectively. The print mode depends on the Print Quality
  565.         setting in the Print menu. Typical settings are lp (System V) or
  566.         lpr (BSD). ASCII and PostScript spoolers can be set independently
  567.         in case special PostScript options or lptops scripts need to be
  568.         run. Full shell syntax (using the shell in $SHELL) is supported,
  569.         including pipes and redirections.
  570.     
  571.     Summary lines: the number of lines displayed in the summary window below
  572.         the search area. This choice takes effect only when grok is restarted.
  573.  
  574.     Card scaling factor: if the screen resolution is very low, it may be
  575.         necessary to enter a number less than 1 to reduce the sizes of items
  576.         in the card at the bottom of the screen. 0.75 or 0.5 are recommended.
  577.         This takes effect only when the next database is loaded.
  578. %% pref_done
  579.     DONE
  580.  
  581.     Remove the preferences menu, and write the changes back to
  582.     the ~/.grok/.grokrc file.
  583. %% queries
  584.     DEFAULT QUERIES
  585.  
  586.     There are four columns of buttons:
  587.  
  588.     - If the button in the first column is off, the query is disabled. The
  589.       query will stay in the Default Query popup, but will not appear in
  590.       the Query pulldown in the main window.
  591.  
  592.     - Only one button can be on in the second column. The column with
  593.       this button on, if any, selects the query that is executed when the
  594.       database is read from disk. If no button in the second column is on,
  595.       no query is done on startup and all cards are shown in the summary
  596.       (unless a query was specified on the command line). The button in
  597.       the first column need not be on for a default query.
  598.  
  599.     - The Name column specifies the string that will be displayed in the
  600.       Query pulldown in the main window.
  601.  
  602.     - The Query Expression column specifies an expression that determines
  603.       which cards to display in the summary when <Name> is selected in the
  604.       Query pulldown in the main window. The expression is applied to all
  605.       cards in the database in turn, and all cards that match are put into
  606.       the summary. An expression is said to match if it begins with a '{'
  607.       and returns a non-null string that does not begin with 'f' after stripping
  608.       leading white space; or if it begins with '(' and returns a string that is
  609.       not numerically equal to zero.
  610.  
  611.     For a description of legal search expression, choose Help->Grammar, or
  612.     refer to the User's Manual.
  613. %% dq_delete
  614.     DELETE
  615.  
  616.     To delete a query, press on its Name or Query Expression button, and
  617.     press the Delete button. Pressing Delete again will delete the next
  618.     query which took the previously deleted query's place. Delete cannot
  619.     be undone.
  620. %% dq_dupl
  621.     DUPLICATE
  622.  
  623.     To duplicate a query, press on its Name or Query Expression button, and
  624.     press the Duplicate button. The new query will be inserted just below
  625.     the duplicated query. After duplicating, edit the Name and Expression.
  626. %% dq_done
  627.     DONE
  628.  
  629.     Remove the Default Query popup. The queries will be written into the
  630.     form file in when the Done button is pressed in the Form Editor window
  631.     (which contains the Queries button that installed the Default Query
  632.     popup).
  633. %% edit
  634.     FORM EDITOR
  635.  
  636.     A form is a description of a card, which presents the contents of a
  637.     database. A database is just an anonymous two-dimensional array of
  638.     strings. The first step when creating a form is naming the form and
  639.     the database it presents. The form name is the name that appears in
  640.     the Database pulldown in the main menu (it's called the Database
  641.     pulldown because users need not be aware of the distinction between
  642.     forms and databases). The database is named separately.
  643.  
  644.     Both the form name and database names are also the file names the
  645.     form and the database will be stored in. The form name gets the
  646.     extension ".gf", and non-procedural databases get the extension ".db"
  647.     tacked on if the names are not fully qualified (i.e., do not begin with
  648.     / or ~). The default directory for forms is ~/.grok and the default
  649.     directory for databases is the directory the form was read from. See
  650.     the Help->Database popup to see which paths are actually used.
  651.  
  652.     The next step is specifying the field delimiter. Databases are two-
  653.     dimensional arrays of strings. Rows are separated by newlines and
  654.     columns are separated by the field delimiter. Default is a colon.
  655.     The /etc/passwd file, for example, is an example of a database with a
  656.     colon as the field separator. The \t and \123 notations are supported.
  657.  
  658.     A read-only database does not permit the user to use the Save item
  659.     in the File pulldown; it will not be possible to change the database.
  660.     Procedural databases are not read from a file but from a program; the
  661.     database string is a shell string that grok will call with a first argument
  662.     "-r" (when reading the database) or "-w" (when saving the database),
  663.     and the form name as entered in the top line as second argument.
  664.  
  665.     The comment should contain the author of the form and its version.
  666.  
  667.  
  668.  
  669.     CANVAS
  670.  
  671.     After specifying the general form parameters, fields can be added to
  672.     the form canvas, or existing fields can be clicked in the canvas and
  673.     modified or deleted. The canvas is a separate window that contains
  674.     a simplified representation of the card as it will appear in the main
  675.     menu when loaded. Changing the size of the canvas window will change
  676.     the size of the card. It is often a good idea to start with a window
  677.     size that is too large and shrink it as the last step.
  678.  
  679.     The canvas has two sections, the "static" part at the top and the
  680.     "card" part at the bottom. Both are separated by a divider that can be
  681.     dragged vertically by clicking and dragging the small square sash near
  682.     the right end of the divider line, which is at the top edge of the
  683.     canvas by default. Fields placed above the divider go into the static
  684.     part; fields placed below the divider go into the card part. The static
  685.     part stays active and sensitive independently of the card being
  686.     displayed; general statistics and card-independent buttons are normally
  687.     placed here. The card part changes with every new card that is selected,
  688.     fields that display data from the card must be in this part.
  689.  
  690.     The static and card part are very similar. Generally, fields of type
  691.     Input, Time, Note, Choice, Flag, and everything else (such as Print)
  692.     that refers fields in the current card (using expression terms such as
  693.     "_fieldname") must go into the card part so it can be desensitized if
  694.     no card is selected. Putting such fields in the static part would allow
  695.     the user to enter data into nonexisting cards because the field would
  696.     not get desensitized when no card is displayed. This is not enforced.
  697.  
  698.  
  699.  
  700.     FIELDS
  701.  
  702.     Fields are either choice or toggle buttons or text entry buttons that
  703.     represent a string in the database, or decorative fields such as
  704.     labels, or text strings that compute values based on strings in the
  705.     database (any string, not just one in the current card). There are
  706.     various options for fields that can be specified in the inset control
  707.     area in the lower section of the form editor. Note that the Choice
  708.     type is the only one that is not autonomous; Choice fields are linked
  709.     with other Choice fields such that only one of the Choice fields with
  710.     identical names can be active at any time. In all other cases, no two
  711.     fields can have the same name.
  712.  
  713.     For a detailed description of the different types of fields, and for a
  714.     description of the grammar of the simple query language that can be
  715.     used for defaults or queries, see the programmer's manual that is
  716.     distributed as a PostScript document as part of the release. The
  717.     Help->Grammar popup in the main window gives a quick reference.
  718.  
  719.  
  720.  
  721.     BUTTONS
  722.  
  723.     A preview function is available for viewing the card as it will appear
  724.     in the main window. The Done button saves the form and exits the form
  725.     editor. Before saving, the form will be checked; a window with error
  726.     messages will appear and the form editor will refuse to save if the
  727.     form contains errors. The form can also be checked with the Debug
  728.     button; no window will appear if no errors are found. The Cancel button
  729.     will discard the edited form and exit the form editor without saving.
  730.  
  731.     The Queries button allows entry of the queries that appear in the
  732.     Queries pulldown in the main menu. Queries are search expressions
  733.     that select a certain subset of available cards, and put the cards
  734.     that satisfied the expression in the summary for the user to select.
  735.  
  736.     The Def Help button attaches a help text to the form. An editor is
  737.     started that allows entering a text describing the current form, and
  738.     how to use the fields and buttons. This help text will be displayed
  739.     when the user presses the Help button in the lower right corner of
  740.     the main window, in addition to some general text that grok adds.
  741. %% form_cancel
  742.     CANCEL
  743.  
  744.     Press OK to exit the form editor without writing changes to disk,
  745.     if you made any. (The confirmation popup will appear even if the
  746.     form did not change.)
  747. %% procdbedit
  748.     PROCEDURAL DATABASE
  749.  
  750.     If the Edit button in the form editor is pressed, the `procedural' flag
  751.     is turned on. The form's data will then read the database by executing
  752.     a script rather than by opening a file. This editor window lets you
  753.     edit this script.
  754.  
  755.     Scripts should always begin with a line containing
  756.     
  757.       #!/bin/sh 
  758.     
  759.     or something similar. The script gets two arguments when executed:
  760.     $1 is either "-r" or "-w". If $1 is "-r", the script is supposed to print
  761.     the generated database data to stdout, using echo or something
  762.     similar, one card per line consisting of fields separated by the form's
  763.     field delimiter character (a colon `:' by default). Trailing blank fields
  764.     and trailing field delimiters can be omitted. If $1 is "-w", grok will print
  765.     the database in the same format to stdin of the script, without trailing
  766.     blank fields or colons. The second argument, $2, is the name of the
  767.     form as entered in the top button in the form editor window, without
  768.     path and without ".gf" extension.
  769.  
  770.     The permissions of the file will be changed to 700 (read, write,
  771.     execute for the owner only) when it is written back.
  772.  
  773.     There is no way to return error conditions.
  774. %% fe_form
  775.     FORM AND DATABASE NAME
  776.  
  777.     The form name is the name that appears in the Database pulldown
  778.     in the main menu (it's called the Database pulldown because users
  779.     need not be aware of the distinction between forms and databases).
  780.     A database is always referenced by the name of the form that
  781.     describes its layout. When a new form or database is created, a
  782.     new unique name must be chosen.
  783.  
  784.     Both the form name and database names are also the file names the
  785.     form and the database will be stored in. The form name gets the
  786.     extension ".gf", and non-procedural databases get the extension ".db"
  787.     tacked on if the names are not fully qualified (i.e., do not begin with
  788.     / or ~). If the database is procedural, the database file is a script, and
  789.     has no .db or any other extension. This script is executed to read or
  790.     write data. See help on the Edit button for details.
  791.  
  792.     When a database or form is read, the path it was read from is stored;
  793.     when the database or form is changed, it is written back to that path.
  794.     When a new database is created, and its name does not begin with /
  795.     or ~ as defined in the second line of the form editor, it is stored in
  796.     the same directory as its form file. The default is always ~/.grok.
  797.     See the Help->Database popup to see which paths are actually used.
  798. %% fe_delim
  799.     DATABASE FIELD DELIMITER
  800.  
  801.     Databases are two-dimensional arrays of strings; rows are separated
  802.     by newlines and columns are separated by the field delimiter. Default
  803.     is a colon. The /etc/passwd file, for example, is an example of a
  804.     database with a colon as the field separator. \t and \123 notations are
  805.     accepted. \0 and \n cannot be used as field delimiters.
  806. %% fe_rdonly
  807.     READ ONLY
  808.  
  809.     If set, the database is read-only and cannot be written back using the
  810.     File->Save function. The effect is similar to what happens if the user
  811.     has no write permission for the database file.
  812. %% fe_proc
  813.     PROCEDURAL, EDIT
  814.  
  815.     Procedural databases are not read from a file but from a program; the
  816.     database string is a shell string that grok will append "-r" (when
  817.     reading the database) or "-w" (when saving the database) to, followed
  818.     by the form name. That is, when the database "x" (as specified in the
  819.     "Referenced database" field) is read and "procedural" is on, grok will
  820.     execute "x -r formname", and expect "x" to echo a delimiter-separated
  821.     list of strings to stdout. Unless the database is read-only, the script
  822.     must accept data on stdin if it is run as "x -w formname".
  823.  
  824.     An executable can be used in place of a script, but then the Edit
  825.     button cannot and should not be used.
  826. %% fe_query
  827.     QUERIES
  828.  
  829.     The Queries button allows entry of the queries that appear in the
  830.     Queries pulldown in the main menu. Queries are search expressions
  831.     that select a certain subset of available cards, and put the cards
  832.     that satisfied the expression in the summary for the user to select.
  833. %% fe_help
  834.     DEF HELP
  835.  
  836.     The Def Help button attaches a help text to the form. An editor is
  837.     started that allows entering a text describing the current form, and
  838.     how to use the fields and buttons. This help text will be displayed
  839.     when the user presses the Help button in the lower right corner of
  840.     the main window.
  841. %% fe_debug
  842.     DEBUG
  843.  
  844.     Check the form for inconsistencies, and display an error and warning
  845.     popup if problems are found. No popup will appear if the form is free
  846.     of errors. The Done button will do the same checks, and will refuse
  847.     to exit the for editor if problems are found.
  848. %% fe_preview
  849.     PREVIEW
  850.  
  851.     Display a menu with a card as it will appear in the main window. The
  852.     card is not interactive and does not display valid database contents,
  853.     but will show labels with the correct dimensions. This is useful to
  854.     determine whether all labels fit into their allocated size; the canvas
  855.     is not always a good indicator for this.
  856.  
  857.     The preview window will remain on the screen, unchanged, until the
  858.     window manager button in the top left corner of the decoration is
  859.     double-clicked.
  860. %% fe_cancel
  861.     CANCEL
  862.  
  863.     Terminate the form editor without writing back changes. All changes
  864.     that have been made since the form editor was installed are discarded.
  865.     To avoid accidentally losing the changes, a confirmation popup is
  866.     installed; this popup is installed even if no changes have been made.
  867. %% fe_done
  868.     DONE
  869.  
  870.     Check the form. If no errors are found, write the form back to disk
  871.     and terminate the form editor. If errors are found, an error popup lists
  872.     the problems, and the form editor is not terminated. The form editor
  873.     can be terminated without writing back with the Cancel button.
  874. %% fe_add
  875.     ADD
  876.  
  877.     Add a field to the form. The currently selected field, if any (high-
  878.     lighted yellow on the canvas), is duplicated, and reasonable defaults
  879.     are filled in. The new field is put below the bottom field in the
  880.     canvas. If the canvas is too small, it may be positioned off-window
  881.     where it cannot be seen; make the canvas larger in this case.
  882.  
  883.     After adding, the new field is selected, and the buttons below the Add
  884.     button can be used to specify type and attributes of the new field.
  885. %% fe_delete
  886.     DELETE
  887.  
  888.     Delete the currently selected field. The selected field is highlighted
  889.     yellow on the canvas.
  890. %% fe_type
  891.     FIELD TYPE
  892.  
  893.     The type of the field. The type determines the appearance of the field
  894.     as well as its behavior and connection to the database. Some fields
  895.     are connected directly to database fields, others are derived or purely
  896.     decorative. The types are:
  897.  
  898.     Input:  this field allows direct display of database strings. User
  899.             input into this field is copied directly into the database.
  900.  
  901.     Time:   this type is equivalent to Input fields, except that only
  902.             date, time, and duration are displayed and can be entered.
  903.             Four different formats can be selected with Time format.
  904.  
  905.     Note:   this type is also equivalent to Input fields, but supports
  906.             multi-line text. Scrollbars will be displayed if the text
  907.             does not fit into the defined space.
  908.  
  909.     Label:  labels are purely decorative. They are static, no expressions
  910.             can be used for dynamically changing the text. Many other field
  911.             types, such as Input, come with built-in labels.
  912.  
  913.     Print:  print fields look like Input fields, but display the result of
  914.             evaluating an expression. No data can be entered into Print
  915.             fields, they are always read-only.
  916.  
  917.     Choice: all Choice fields that have the same internal field name are
  918.             implicitly connected to the same database string. Only one of
  919.             them can be on. The choice/flag code of the Choice item that
  920.             is on is stored in the database.
  921.  
  922.     Flag:   flag fields are similar to Choice fields, but they are not
  923.             connected to other Flag fields, and must have a unique internal
  924.             name. Their choice/flag code is stored in the database if the
  925.             flag is on. The database string is empty if the flag is off.
  926.  
  927.     Button: buttons execute an expression when pressed.
  928.  
  929.     Chart:  chart fields display statistics in a bar chart. No input is
  930.             possible.
  931.  
  932.     When the type of an existing field is changed, attributes not
  933.     applicable to the new field type will disappear from the menu but
  934.     will be remembered internally, and will be restored when the type is
  935.     changed back, until another form or database is loaded.
  936. %% fe_flags
  937.     FLAGS
  938.  
  939.     Searchable:   all fields marked searchable will be searched when a
  940.                   search string is used in the main menu. Searching means
  941.                   that the referenced database field will be searched, and
  942.                   the card will be put into the summary if a match is found.
  943.  
  944.     Read only:    if set, no data can be entered. Read-only input or time
  945.                   fields are displayed with a gray background.
  946.  
  947.     Not sortable: fields that are not sortable will not appear in the Sort
  948.                   pulldown in the main menu.
  949.  
  950.     Default sort: only one field can have the default sort flag set. This
  951.                   field is the field the database will be sorted by when
  952.                   the database is loaded from disk. It is also the secondary
  953.                   sort criterium if the user re-sorts the database with the
  954.                   Sort pulldown.
  955.  
  956.     If a flag of a Choice item is changed, the same flag of all Choice
  957.     items with the same internal field name is also changed.
  958. %% fe_int
  959.     INTERNAL FIELD NAME
  960.  
  961.     The internal field name is a unique identifier for a field. Fields that
  962.     reference a database column, such as Input or Flag fields, implicitly
  963.     name the database column. For example, if database column 3 is shown
  964.     in an Input field named "three", then the database column 3 can be
  965.     referenced in expressions as either "_3" or "_three". The first database
  966.     column is number 0.
  967.  
  968.     Choice fields are an exception to the uniqueness rule. Multiple Choice
  969.     fields can share an internal field name. All choice fields with the same
  970.     field name write into the same database column (which means that
  971.     their Database column number must also agree). Grok makes sure that
  972.     only one of the choice fields with matching field names is on at any
  973.     time. When changing attributes such as flags or input defaults of a
  974.     Choice item, all other choice items with the same name also change.
  975.  
  976.     The field name is a constant. No expression is allowed.
  977. %% fe_column
  978.     DATABASE COLUMN
  979.  
  980.     Fields that reference a database column must specify which column.
  981.     Columns are numbered from 0. No two fields can reference the same
  982.     column, with the exception of choice fields (only one of which can
  983.     be on at any time), because that would have the side effect of giving
  984.     more than one name to a database column. See Internal field name.
  985.  
  986.     It is usually a good idea to number database columns consecutively,
  987.     and not omit any column number unless a database column exists but
  988.     is not used by the form.
  989.  
  990.     If the database column of a Choice item is changed, the column of all
  991.     Choice items with the same internal field name is also changed.
  992.  
  993.     The database column is a constant. No expression is allowed.
  994. %% fe_sum
  995.     SUMMARY COLUMN, WIDTH
  996.  
  997.     If the width is nonzero, the field is put into the summary in the main
  998.     window. The width is the number of characters that go into the list.
  999.     Grok separates columns by two spaces. The sum of all widths should
  1000.     not exceed 79 because they would get truncated to 79 characters
  1001.     when printed (File->Print can print summaries).
  1002.  
  1003.     The summary column specifies the order of fields with nonzero summary
  1004.     widths in the summary. The fields with the lowest summary column number
  1005.     appears in the leftmost column. It is not necessary to choose column
  1006.     numbers consecutively, they define the sort order and not absolute
  1007.     column numbers. No two fields (except choice fields that also also
  1008.     share the internal field name) may have the same summary column
  1009.     number if they have a nonzero width.
  1010.  
  1011.     If the summary column or width of a Choice item is changed, the column
  1012.     and width of all Choice items with the same internal field name are
  1013.     also changed.
  1014.  
  1015.     The summary column and width are constants. No expressions are
  1016.     allowed.
  1017. %% fe_flag
  1018.     CHOICE/FLAG CODE
  1019.  
  1020.     Choice and Flag codes specify the string that gets put into the
  1021.     database if the choice or flag field is "on". This code is a static string.
  1022.     All choice codes for one database column should all be different, and
  1023.     care should be taken that all possible codes that can appear in the
  1024.     database have a Choice field with a matching code.
  1025.  
  1026.     If the flag code matches the database string, the string specified in
  1027.     the "shown in summary as" button is put into the summary if the
  1028.     Summary width number is greater than 0. The flag codes themselves
  1029.     are usually too unmnemonic for the summary. Note that if the database
  1030.     is sorted by this column, it is sorted by the database string and not
  1031.     the string in the summary.
  1032. %% fe_time
  1033.     TIME FORMAT
  1034.  
  1035.     Time fields can have one of four display formats:
  1036.  
  1037.     Date:      A date in day.month.year or month/day/year format, depending
  1038.                on the setting in the File->Preferences menu. The date may
  1039.                have a time part that is not displayed.
  1040.  
  1041.     Time:      A time in hour:minute [ap] format. US format is enabled with
  1042.                the File->Preferences menu. The time may have a date part
  1043.                that is not displayed.
  1044.  
  1045.     Date+time: Both the date and the time are displayed, date first.
  1046.  
  1047.     Duration:  The number is interpreted as a number of seconds, and is
  1048.                displayed in hour:minute (no a/p) format.
  1049.     
  1050.     Note that internal calculations are always done in seconds. If the
  1051.     result is not in the range used by the time format (such as numbers
  1052.     greater than 24*60*60 for Time, or numbers not dividable by 24*60*60
  1053.     without remainder for Date) are displayed by ignoring the undisplayed
  1054.     part. This may give unexpected results when sorting.
  1055. %% fe_ljust
  1056.     LABEL JUSTIFICATION
  1057.  
  1058.     The label may be left-justified, centered, or right-justified in the
  1059.     space allocated for it on the canvas. This not only applies to Label
  1060.     fields, but also to the label part (left or top part) of Input, Time,
  1061.     Note, Flag, and Choice fields. Use the Preview button to see the effect.
  1062. %% fe_lfont
  1063.     LABEL FONT
  1064.  
  1065.     The label can be displayed as Helvetica, Helvetica Oblique (slanted),
  1066.     Helvetica Narrow, Helvetica Bold (large), or Courier. The Helvetica
  1067.     fonts are proportionally-spaced; the Courier font is fixed size (all
  1068.     characters have the same width).
  1069.  
  1070.     It is recommended that Helvetica is used for labels, and Courier is
  1071.     used as input font for Input, Time, and Note fields. It is highly
  1072.     recommended to use Courier as input font for Note fields because
  1073.     printing functions (File->Print) print notes using a fixed-size font.
  1074. %% fe_ltxt
  1075.     LABEL TEXT
  1076.  
  1077.     Most fields have a label part that display a static text as entered
  1078.     as label text. No expressions are allowed. Use the Preview button to
  1079.     display the result to make sure that the text fits into the allocated
  1080.     space.
  1081. %% fe_ijust
  1082.     INPUT JUSTIFICATION
  1083.  
  1084.     The input may be left-justified, centered, or right-justified in the
  1085.     space allocated for it on the canvas. Fields that allow text input
  1086.     include Input, Time, and Note fields. Left justification is recommended.
  1087. %% fe_ifont
  1088.     INPUT FONT
  1089.  
  1090.     The input can be displayed as Helvetica, Helvetica Oblique (slanted),
  1091.     Helvetica Narrow, Helvetica Bold (large), or Courier. The Helvetica
  1092.     fonts are proportionally-spaced; the Courier font is fixed size (all
  1093.     characters have the same width). Fields that allow text input include
  1094.     Input, Time, and Note fields.
  1095.  
  1096.     It is recommended that Helvetica is used for labels, and Courier is
  1097.     used as input font for Input, Time, and Note fields. It is highly
  1098.     recommended to use Courier as input font for Note fields because
  1099.     printing functions (File->Print) print notes using a fixed-size font.
  1100. %% fe_range
  1101.     MAX INPUT LENGTH
  1102.  
  1103.     The maximum input length determines the maximum number of characters
  1104.     that can be entered into Input, Time, and Note fields. The default is
  1105.     100 for Input and Time fields, and 10000 for Note fields. When the
  1106.     maximum is reached, the field will stop accepting keyboard input. It
  1107.     is a common and annoying error to use a number that is too small for
  1108.     Note fields. There is no space saving in the database, and little
  1109.     space saving overall, in using low numbers. The maximum input length
  1110.     is a constant, no expression may be used.
  1111. %% fe_def
  1112.     INPUT DEFAULT
  1113.  
  1114.     For fields that can be used to change the database, such as Input
  1115.     fields, this string specifies the default value when a new card is
  1116.     created using the New button at the bottom of the main window. This
  1117.     string can be an expression.
  1118.  
  1119.     If the input default of a Choice item is changed, the default of all
  1120.     Choice items with the same internal field name is also changed. The
  1121.     default for a choice item should evaluate to one of the flag/choice
  1122.     codes of the Choice items, or new cards will be created with none
  1123.     of the alternatives set.
  1124.  
  1125.     NOTE -- if the field has type Time, the input default expression
  1126.     should evaluate to a number of seconds, not to a string containing
  1127.     a date. For example, to make the Time field default to today, use
  1128.     (date), not {date}.
  1129. %% fe_pattern
  1130.     INPUT PATTERN
  1131.  
  1132.     This string is a mask that user input must satisfy to be accepted as
  1133.     input and stored into the database. It can be an expression.
  1134. %% fe_gray
  1135.     GRAYED OUT IF
  1136.  
  1137.     If the expression evaluates to true, the field is grayed out and can
  1138.     not be manipulated by the user. The expression is re-evaluated when
  1139.     the user changes another field. This can be used to disallow entry
  1140.     into fields under certain conditions. See also the help text on the
  1141.     skip-if expression button.
  1142. %% fe_inv
  1143.     INVISIBLE IF
  1144.  
  1145.     If the expression evaluates to true after the database has been read
  1146.     in, the field will not be displayed in the card, leaving empty space.
  1147.     Unlike Grayed-out-if, it is evaluated only once when the database is
  1148.     read. This can be used, for example, to hide database fields when the
  1149.     wrong user accesses the database by using an expression using the
  1150.     "user" or "uid" keywords.
  1151. %% fe_ro
  1152.     READ-ONLY IF
  1153.  
  1154.     If the expression evaluates to true after the database has been read
  1155.     in, the field will not allow input into the database, as if the
  1156.     Read-only flag had been set in the form editor. Like Invisible-if, it
  1157.     is evaluated only once when the database is read. This can be used,
  1158.     for example, to disallow other users from changing certain database
  1159.     fields by using an expression using the "user" or "uid" keywords.
  1160. %% fe_skip
  1161.     SKIP IF
  1162.  
  1163.     When the user enters data and presses the Return key on an Input
  1164.     or Time field, grok puts the cursor into the next field automatically.
  1165.     The next field is the next field to the right if there is one in the
  1166.     same row, or the next one below otherwise. The next field is skipped
  1167.     if its skip-if expression evaluates to TRUE at the time of the search,
  1168.     and the search continues with the next field after that.
  1169.  
  1170.     This can be used to lead the user to the next field applicable to
  1171.     entries done earlier; for example, the ``maiden name'' field in a
  1172.     rolodex application could be skipped if an earlier Choice button
  1173.     indicates that the person is male.
  1174.  
  1175.     Skip-if does not prevent users from pressing on the skipped button
  1176.     explicitly. Use `grayed-out-if' to prevent that.
  1177. %% fe_press
  1178.     ACTION WHEN PRESSED
  1179.  
  1180.     If the type of the field is Button, this expression is evaluated when
  1181.     the user presses the button. This will generally be an expression with
  1182.     a side effect, such as an assignment to a variable, or a `switch' or a
  1183.     `system' function. The latter calls a Unix system function.
  1184. %% fe_result
  1185. %% fe_query
  1186. %% grammar
  1187.     GRAMMAR
  1188.  
  1189.     This is a quick reference only. For details, refer to the manual. n
  1190.     stands for numerical expressions, and s stands for string expressions.
  1191.     In general, numerical expressions are enclosed in (), and string
  1192.     expressions are enclosed in {}. Booleans use 0 or "0" for false and 1
  1193.     or "1" for true. Note that short-circuiting with ?: && || does not work.
  1194.  
  1195.     Numerical Operations: arithmetic operators use standard C precedences.
  1196.  
  1197.       (n)             number
  1198.       {s}             in number context, convert string to a number
  1199.       n ? n : n    select n2 if n1 is nonzero, n3 if zero
  1200.       n , n          evaluate both numbers, return second
  1201.       -n            sign change
  1202.       !n              boolean NOT
  1203.       ~n             bitwise NOT
  1204.       n + n         add
  1205.       n - n         subtract
  1206.       n * n         multiply
  1207.       n / n          divide, n/0 is 1
  1208.       n % n        modulus, n%0 is 1
  1209.       n & n        bitwise AND
  1210.       n && n      boolean AND
  1211.       n | n          bitwise OR
  1212.       n || n         boolean OR
  1213.       n ^ n         bitwise XOR
  1214.       n << n       bitwise left shift
  1215.       n >> n       bitwise right shift
  1216.       n == n       equal
  1217.       n != n        not equal
  1218.       n < n         less than
  1219.       n > n         greater than
  1220.       n <= n       less than or equal
  1221.       n >= n       greater than or equal
  1222.       sqrt (n)      square root
  1223.       exp (n)       exponential
  1224.       log (n)        logarithm to base 10
  1225.       ln (n)          logarithm to base e
  1226.       pow(n, n)    n1 raised to n2
  1227.       sin (n)        sine
  1228.       cos (n)       cosine
  1229.       tan (n)        tangent
  1230.       asin (n)      arc sine
  1231.       acos (n)     arc cosine
  1232.       atan (n)      arctangent
  1233.       atan2(n,n)  quadrant-aligned arctangent
  1234.       len (s)        string length
  1235.       bound(n,n,n)   n1 bounded by n2 and n3
  1236.  
  1237.  
  1238.     String Operations: note that string comparisons return strings, and
  1239.     must be enclosed in braces {} if && or || or other numerical operators
  1240.     are used on the result. Printf arguments generally need to be
  1241.     parenthesized also.
  1242.  
  1243.       "string"      literal string
  1244.       {s}             string
  1245.       (n)             in string context, convert number to string
  1246.       s ; s           evaluate both strings, return second
  1247.       s . s           concatenate strings
  1248.       s ? s : s     select s2 if s1 evaluates nz, s3 if zero
  1249.       s == s       strings are equal
  1250.       s != s         strings are not equal
  1251.       s < s          lexicographically less than
  1252.       s > s          lexicographically greater than
  1253.       s <= s        lexicographically less than or equal
  1254.       s >= s        lexicographically greater than or equal
  1255.       chop(s)      s without trailing newline
  1256.       substr(s,n,n)  substring of the s1; n1 is start index and n2 is length
  1257.       printf (args)   formatted string, args is comma-separated expr list
  1258.  
  1259.  
  1260.     Variables: variables are letters a through z that can hold strings or
  1261.     numbers. When a variable is assigned to, the result of the assignment
  1262.     is returned. All variables are reset to the empty string (or 0) when a
  1263.     database is loaded from disk.
  1264.  
  1265.       var              value of variable
  1266.       var = s        assign string to variable
  1267.       var = n        assign number to variable
  1268.       var .= s        append string to variable
  1269.       var += n      add number to variable
  1270.       var -= n      subtract number from variable
  1271.       var *= n      multiply variable by number
  1272.       var /= n       divide variable by number
  1273.       var %= n     assign modulo with number to variable
  1274.       var &= n      logical AND with variable
  1275.       var |= n        logical OR with variable
  1276.       var++          post-increment
  1277.       var--          post-decrement
  1278.       ++var          pre-increment
  1279.       --var          pre-decrement
  1280.  
  1281.  
  1282.     Database Access
  1283.  
  1284.       _field             database field of current card, field is number or name
  1285.       _field [n]        database field from any card
  1286.       this                number of current card, 0 is first
  1287.       last                number of last card
  1288.       avg (_field)    average of field in all cards
  1289.       qavg (_field)   average of field in current query result
  1290.       dev (_field)    standard deviation of field in all cards
  1291.       qdev (_field)   standard deviation of field in current query result
  1292.       min (_field)    minimum value of field in all cards
  1293.       qmin (_field)   minimum value of field in current query result
  1294.       max (_field)   maximum value of field in all cards
  1295.       qmax (_field)  maximum value of field in current query result
  1296.       sum (_field)   sum of field in all cards
  1297.       qsum (_field)  sum of field in current query result
  1298.       dbase            name of current database file
  1299.       form              name of the current file
  1300.       prevform       name of the previous form file
  1301.  
  1302.       search("", "")              do nothing
  1303.       search("", "*")            put all cards in summary
  1304.       search("", "{expr}")    all cards for which {expr} is not "0" or empty
  1305.       search("", "(expr)")    all cards for which (expr) is not 0
  1306.       search("", "string")     all cards that contain search string
  1307.       search("name", "x")   switch to form "name", then do query "x"
  1308.  
  1309.  
  1310.     Operating System Access
  1311.  
  1312.       system (s)      execute shell command and return stdout
  1313.       $envvar         environment variable
  1314.       host               local host name
  1315.       user               user's login name
  1316.       uid                 user's numeric user ID
  1317.       gid                 user's numeric group ID
  1318.       access(s,n)   1 if any/r/w/x permission for file s for n=0/1/2/4
  1319.       beep              ring terminal bell, return ""
  1320.       error (args)    like printf but into a window, return ""
  1321.  
  1322.  
  1323.     Time Conversion: dates and times are stored as number of seconds since
  1324.     January 1, 1970. Durations are stored as number of seconds. Note that
  1325.     this means that a time is a significantly larger number than a duration,
  1326.     even if both have the same hh:mm string representation.
  1327.  
  1328.       time               current time as hh:mm or hh:mm[ap]
  1329.       time (n)          number as hh:mm or hh:mm[ap]
  1330.       date               today's date as dd.mm.yy or mm/dd/yy
  1331.       date (n)         number as dd.mm.yy or mm/dd/yy
  1332.       duration(n)    number of seconds as hh:mm
  1333.       date              seconds since January 1, 1970
  1334.       year (n)         n as four-digit year
  1335.       month (n)      n as month 1..12
  1336.       day (n)          n as day 1..31
  1337.       hour (n)         n as hour 0..23
  1338.       minute (n)      n as minute 0..59
  1339.       second (n)     n as second 0..59
  1340.       julian (n)        n as julian date 0..365
  1341.       leap (n)         1 if the time n is in a leap year, 0 otherwise
  1342.